Skip to main content

Getting started

Glossary / Quick Links​

Windows Installation​

Prerequisites for Installation​

For installation directly under C:/ administrator rights are required, otherwise the work environment can also be created in the user directory (C:/Users/[Username]).

Add each to PATH, log out/log in if necessary or at least reopen CMD if already open.

1. Create local folder and clone project from Github​

  1. Create and open folder (in this guide ~/Bildungscloud/ is used as path)

    cd /d C:/ && md Bildungscloud && cd Bildungscloud

  2. Clone repositories

    git clone https://github.com/hpi-schul-cloud/schulcloud-server
    git clone https://github.com/hpi-schul-cloud/schulcloud-client
    git clone https://github.com/hpi-schul-cloud/nuxt-client

    Not necessary for running Bildungscloud, but still interesting for developers are the repositories for our End-2-End tests and the Deployment.

2. Set up database​

  • Create database folder

    md C:/Bildungscloud/db

  • Install MongoDB (Community Server)

  • Start database (adjust version and path accordingly beforehand)

    "C:\Program Files\MongoDB\Server\5.0\bin\mongod" --dbpath "D:\apps\SchulCloud\db"

  • Fill database with test data

    In the schulcloud-server folder:

    npm run setup:db:seed

  • Install MongoDB Compass to view the database

3. Set up server​

Prerequisites​

Start server​

  • Start RabbitMQ

    docker run -d -p 5672:5672 -p 15672:15672 --name rabbitmq rabbitmq:3.8.9-management

  • Start server

    npm run nest:start:dev

    (or npm run nest:start:debug)

Successful if http://localhost:3030/ shows the feathers start page.

4. Set up Legacy Client (schulcloud-client)​

  • Install packages

    npm i -g nodemon
    cd schulcloud-client && npm ci

  • Build client

    npm run build

  • Start client

    npm run watch

Successful if http://localhost:3100/ shows the Bildungscloud start page.

5. Set up Nuxt Client​

  • Install packages

    npm ci

  • Start Nuxt Client

    npm run serve

Successful if http://localhost:4000/ shows the Bildungscloud start page.

Possible Issues​

Installation for MacOS (Intel & Apple M1 Chip)​

Prerequisites​

  • Install Homebrew (incl. Xcode Command Line Tools, if not available)
  • Install Git if not available
  • Install Node (check version, see package.json)
    • nvm (Node Version Manager) is recommended

1. Create local folder and clone project from Github​

  1. Create and open folder (in this guide ~/Bildungscloud/ is used as path)

    mkdir Bildungscloud && cd Bildungscloud

  2. Clone repositories

    git clone https://github.com/hpi-schul-cloud/schulcloud-server
    git clone https://github.com/hpi-schul-cloud/schulcloud-client
    git clone https://github.com/hpi-schul-cloud/nuxt-client

    Not necessary for running Bildungscloud, but still interesting for developers are the repositories for our End-2-End tests and the Deployment.

2. Set up database​

  • Create database folder

    mkdir ~/Bildungscloud/db

  • Install MongoDB (Community Server)

    brew tap mongodb/brew
    brew install mongodb-community@5.0

  • Fill database with test data

    In the schulcloud-server folder:

    npm run setup:db:seed

  • Install MongoDB Compass to view the database

  • A few helpful tips for working with MongoDB: https://docs.dbildungscloud.de/x/NIJdD

2.1 Updating mongo version on Mac if used via homebrew service (tested on MacBook Pro M1 Max, August 2025)​

  1. stop recent service: brew services stop mongodb/brew/mongodb-community@_VERSION_

    1. check activity window if mongod is not present anymore
    2. check list of current homebrew services and check for stoped service: brew services list

  2. uninstall recent version (if no local database backup necessary): brew uninstall mongodb/brew/mongodb-community@_VERSION_

    1. brew autoremove to remove unneeded dependencies
    2. check brew services list, recent mongodb version should not be present anymore

  3. remove old db data within /opt/homebrew/var with rm -rf mongodb and simply create the new empty folder mkdir /opt/homebrew/var/mongodb (or remove content of folder itself, what ever is easier for you)

  4. go to /opt/homebrew/etc and check mongod.conf if value storage.dbPath is set to before created folder /opt/homebrew/var/mongodb

  5. install new version with brew install mongodb/brew/mongodb-community@_NEW_VERSION_

  6. check /opt/homebrew/opt if correct service is present (and old one is gone)

  7. check for working mongod service with correct config: mongod --config /opt/homebrew/etc/mongod.conf

  8. stop mongod and simply leave homebrew service running in the background with brew services start mongodb/brew/mongodb-community@_NEW_VERSION_

  9. check list of current homebrew services and check for started service: brew services list

  10. be happy and use your wished database software (e.g. Studio 3T), connect to your local db and check if db.version() suits your desired version

  11. (beforehand of course seed your local database with e.g. npm run setup:db:seed in server)

3. Set up server​

Prerequisites (Apple M1 Chip)​

  • Install CMake (via Homebrew)

    brew install cmake

Prerequisites (Intel & Apple M1 Chip)​

  • Install packages

    cd schulcloud-server && npm ci

  • Install Docker

  • Install RabbitMQ (via Homebrew)

    brew install rabbitmq

Start server​

  • Start database

    brew services start mongodb-community@5.0

  • Start RabbitMQ

    docker run -d -p 5672:5672 -p 15672:15672 --name rabbitmq rabbitmq:3.8.9-management

  • Start server (automatic reload after saving changes)

    npm run nest:start:dev

    (or npm run nest:start:debug)

Successful if http://localhost:3030/ shows the feathers start page.

4. Set up Legacy Client (schulcloud-client)​

  • Install packages

    cd schulcloud-client && npm ci

  • Build client (style adjustments are only correctly considered after this command)

    npm run build

  • Start client (automatic reload after saving changes)

    npm run watch

  • Choose different theme (e.g. N21)

    declare -x SC_THEME="n21"
    npm run build
    npm run start

Possible Issues​

  • Python is required, sometimes despite existing Python 3 version an attempt is made to reinstall the CommandLineTools of MacOS. Can be provoked with the command python -v

    First check if the directory /Library/Developer/CommandLineTools exists. If yes, install python via homebrew if not already done (in the latest version) and then copy the following lines to the known path collection of the system considering the current version:

    /opt/homebrew/opt/python@3.9/libexec/bin
    /opt/homebrew/bin/python3

Successful if http://localhost:3100/ shows the Bildungscloud start page.

5. Set up Nuxt Client​

For Apple M1 Chips​

  • Install Google Chrome

    This is recommended to avoid installing Chromium. For development and testing, common browsers should be installed on the system anyway.

  • Bypass Chromium installation

    cd nuxt-client
    export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
    export PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

    or

    cd nuxt-client
    export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
    export PUPPETEER_EXECUTABLE_PATH="which chromium"

For Intel & Apple M1 Chips​

  • Install packages

    npm ci

  • Start Nuxt Client (automatic reload after saving changes)

    npm run serve

  • Choose different theme (e.g. N21)

    declare -x SC_THEME="n21"
    npm run build
    npm run start

Successful if http://localhost:4000/ shows the Bildungscloud start page.

Possible Issues​

If you get the following error message when running npm ci:

Canvas Installation Error (click to expand)
npm ERR! code 1
npm ERR! path /Users/AdminUser/Bildungscloud/nuxt-client/node_modules/canvas
npm ERR! command failed
npm ERR! command sh -c node-pre-gyp install --fallback-to-build --update-binary
npm ERR! Failed to execute '/Users/AdminUser/.nvm/versions/node/v18.16.1/bin/node /Users/AdminUser/.nvm/versions/node/v18.16.1/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js configure --fallback-to-build --update-binary --module=/Users/AdminUser/Bildungscloud/nuxt-client/node_modules/canvas/build/Release/canvas.node --module_name=canvas --module_path=/Users/AdminUser/Bildungscloud/nuxt-client/node_modules/canvas/build/Release --napi_version=8 --node_abi_napi=napi --napi_build_version=0 --node_napi_label=node-v108' (1)
npm ERR! node-pre-gyp info it worked if it ends with ok
npm ERR! node-pre-gyp info using node-pre-gyp@1.0.10
npm ERR! node-pre-gyp info using node@18.16.1 | darwin | arm64
npm ERR! node-pre-gyp http GET https://github.com/Automattic/node-canvas/releases/download/v2.11.0/canvas-v2.11.0-node-v108-darwin-unknown-arm64.tar.gz
npm ERR! node-pre-gyp ERR! install response status 404 Not Found on https://github.com/Automattic/node-canvas/releases/download/v2.11.0/canvas-v2.11.0-node-v108-darwin-unknown-arm64.tar.gz 
npm ERR! node-pre-gyp WARN Pre-built binaries not installable for canvas@2.11.0 and node@18.16.1 (node-v108 ABI, unknown) (falling back to source compile with node-gyp) 
npm ERR! node-pre-gyp WARN Hit error response status 404 Not Found on https://github.com/Automattic/node-canvas/releases/download/v2.11.0/canvas-v2.11.0-node-v108-darwin-unknown-arm64.tar.gz 
npm ERR! gyp info it worked if it ends with ok
npm ERR! gyp info using node-gyp@9.4.0
npm ERR! gyp info using node@18.16.1 | darwin | arm64
npm ERR! gyp info ok 
npm ERR! gyp info it worked if it ends with ok
npm ERR! gyp info using node-gyp@9.4.0
npm ERR! gyp info using node@18.16.1 | darwin | arm64
npm ERR! gyp info find Python using Python version 3.11.4 found at "/opt/homebrew/opt/python@3.11/bin/python3.11"
npm ERR! gyp info spawn /opt/homebrew/opt/python@3.11/bin/python3.11
npm ERR! gyp info spawn args [
npm ERR! gyp info spawn args   '/Users/AdminUser/.nvm/versions/node/v18.16.1/lib/node_modules/npm/node_modules/node-gyp/gyp/gyp_main.py',
npm ERR! gyp info spawn args   'binding.gyp',
npm ERR! gyp info spawn args   '-f',
npm ERR! gyp info spawn args   'make',
npm ERR! gyp info spawn args   '-I',
npm ERR! gyp info spawn args   '/Users/AdminUser/Bildungscloud/nuxt-client/node_modules/canvas/build/config.gypi',
npm ERR! gyp info spawn args   '-I',
npm ERR! gyp info spawn args   '/Users/AdminUser/.nvm/versions/node/v18.16.1/lib/node_modules/npm/node_modules/node-gyp/addon.gypi',
npm ERR! gyp info spawn args   '-I',
npm ERR! gyp info spawn args   '/Users/AdminUser/Library/Caches/node-gyp/18.16.1/include/node/common.gypi',
npm ERR! gyp info spawn args   '-Dlibrary=shared_library',
npm ERR! gyp info spawn args   '-Dvisibility=default',
npm ERR! gyp info spawn args   '-Dnode_root_dir=/Users/AdminUser/Library/Caches/node-gyp/18.16.1',
npm ERR! gyp info spawn args   '-Dnode_gyp_dir=/Users/AdminUser/.nvm/versions/node/v18.16.1/lib/node_modules/npm/node_modules/node-gyp',
npm ERR! gyp info spawn args   '-Dnode_lib_file=/Users/AdminUser/Library/Caches/node-gyp/18.16.1/<(target_arch)/node.lib',
npm ERR! gyp info spawn args   '-Dmodule_root_dir=/Users/AdminUser/Bildungscloud/nuxt-client/node_modules/canvas',
npm ERR! gyp info spawn args   '-Dnode_engine=v8',
npm ERR! gyp info spawn args   '--depth=.',
npm ERR! gyp info spawn args   '--no-parallel',
npm ERR! gyp info spawn args   '--generator-output',
npm ERR! gyp info spawn args   'build',
npm ERR! gyp info spawn args   '-Goutput_dir=.'
npm ERR! gyp info spawn args ]
npm ERR! /bin/sh: pkg-config: command not found
npm ERR! gyp: Call to 'pkg-config pixman-1 --libs' returned exit status 127 while in binding.gyp. while trying to load binding.gyp
npm ERR! gyp ERR! configure error 
npm ERR! gyp ERR! stack Error: `gyp` failed with exit code: 1
npm ERR! gyp ERR! stack     at ChildProcess.onCpExit (/Users/AdminUser/.nvm/versions/node/v18.16.1/lib/node_modules/npm/node_modules/node-gyp/lib/configure.js:325:16)
npm ERR! gyp ERR! stack     at ChildProcess.emit (node:events:513:28)
npm ERR! gyp ERR! stack     at ChildProcess._handle.onexit (node:internal/child_process:291:12)
npm ERR! gyp ERR! System Darwin 22.5.0
npm ERR! gyp ERR! command "/Users/AdminUser/.nvm/versions/node/v18.16.1/bin/node" "/Users/AdminUser/.nvm/versions/node/v18.16.1/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "configure" "--fallback-to-build" "--update-binary" "--module=/Users/AdminUser/Bildungscloud/nuxt-client/node_modules/canvas/build/Release/canvas.node" "--module_name=canvas" "--module_path=/Users/AdminUser/Bildungscloud/nuxt-client/node_modules/canvas/build/Release" "--napi_version=8" "--node_abi_napi=napi" "--napi_build_version=0" "--node_napi_label=node-v108"
npm ERR! gyp ERR! cwd /Users/AdminUser/Bildungscloud/nuxt-client/node_modules/canvas
npm ERR! gyp ERR! node -v v18.16.1
npm ERR! gyp ERR! node-gyp -v v9.4.0
npm ERR! gyp ERR! not ok 
npm ERR! node-pre-gyp ERR! build error 
npm ERR! node-pre-gyp ERR! stack Error: Failed to execute '/Users/AdminUser/.nvm/versions/node/v18.16.1/bin/node /Users/AdminUser/.nvm/versions/node/v18.16.1/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js configure --fallback-to-build --update-binary --module=/Users/AdminUser/Bildungscloud/nuxt-client/node_modules/canvas/build/Release/canvas.node --module_name=canvas --module_path=/Users/AdminUser/Bildungscloud/nuxt-client/node_modules/canvas/build/Release --napi_version=8 --node_abi_napi=napi --napi_build_version=0 --node_napi_label=node-v108' (1)
npm ERR! node-pre-gyp ERR! stack     at ChildProcess.<anonymous> (/Users/AdminUser/Bildungscloud/nuxt-client/node_modules/@mapbox/node-pre-gyp/lib/util/compile.js:89:23)
npm ERR! node-pre-gyp ERR! stack     at ChildProcess.emit (node:events:513:28)
npm ERR! node-pre-gyp ERR! stack     at maybeClose (node:internal/child_process:1091:16)
npm ERR! node-pre-gyp ERR! stack     at ChildProcess._handle.onexit (node:internal/child_process:302:5)
npm ERR! node-pre-gyp ERR! System Darwin 22.5.0
npm ERR! node-pre-gyp ERR! command "/Users/AdminUser/.nvm/versions/node/v18.16.1/bin/node" "/Users/AdminUser/Bildungscloud/nuxt-client/node_modules/.bin/node-pre-gyp" "install" "--fallback-to-build" "--update-binary"
npm ERR! node-pre-gyp ERR! cwd /Users/AdminUser/Bildungscloud/nuxt-client/node_modules/canvas
npm ERR! node-pre-gyp ERR! node -v v18.16.1
npm ERR! node-pre-gyp ERR! node-pre-gyp -v v1.0.10
npm ERR! node-pre-gyp ERR! not ok

Make sure you're using the correct Node version with nvm use and also install the following dependency to install the canvas package:

brew install pkg-config cairo pango libpng jpeg giflib librsvg

After that, npm ci should run without problems.

Setup of Connected Systems​

Set up calendar​

You can set up the calendar service, however, this is not necessary for daily use.

Useful links:

Initial setup:

docker pull postgres
> Using default tag: latest
> latest: Pulling from library/postgres
> 214ca5fb9032: Pull complete
> e6930973d723: Pull complete
> aea7c534f4e1: Pull complete
> d0ab8814f736: Pull complete
> 648cc138980a: Pull complete
> 7804b894301c: Pull complete
> cfce56252c3f: Pull complete
> 8cce7305e3b6: Pull complete
> 8e979d981f07: Pull complete
> 4b0a5f0b050c: Pull complete
> a6bc1be6e5b0: Pull complete
> d115610a4c3b: Pull complete
> bf74ca3879b4: Pull complete
> Digest: sha256:117e7b9287612505575ac11db1cf81742eea6fd5cd8b2ce26e40f366b1f74e25
> Status: Downloaded newer image for postgres:latest
> docker.io/library/postgres:latest

docker image ls
> postgres            latest            dd21862d2f49        9 hours ago         376MB

docker run --name schulcloud_calendar_db -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=schulcloud_calendar -d postgres
> b01c1c21ec1a9c275a7c240a23c905b8316d27bebafbe2bb0046416d032ebd64

docker container list
> CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
> b01c1c21ec1a        postgres            "docker-entrypoint.s…"   2 minutes ago       Up 2 minutes        0.0.0.0:5432->5432/tcp   schulcloud_calendar

// we need to create a user for the db called node with password node for the application
docker exec -it b01c1c21ec1a /bin/bash
root@b1054398dc72:/# psql -U postgres

postgres-# CREATE USER node WITH PASSWORD node;
postgres-# GRANT ALL PRIVILEGES ON DATABASE schulcloud_calendar to node;

exit

// you can test you connection over pgadmin with login as postgres user 
// we need to setup our datatables
// you can also execute the content of schema.sql in pgadmin directly
psql -U node -d schulcloud_calendar -a -f schema.sql  

cd ./schulcloud_calendar
npm run start
> schulcloud-calendar@27.12.0 start
> node src

{
  message: 'Database connected with 14.3 (Debian 14.3-1.pgdg110+1)',
  level: 'alert',
  timestamp: '2022-05-18T09:18:53.713Z',
  logType: 'log'
}

To restart the container later:

// find and start container again
docker ps -a
> CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
> b1054398dc72 postgres "docker-entrypoint.s…" 2 days ago Up 2 minutes 0.0.0.0:5432->5432/tcp schulcloud_calendar_db

docker start b1054398dc72

docker ps
> b1054398dc72 postgres "docker-entrypoint.s…" 2 days ago Up 2 minutes 0.0.0.0:5432->5432/tcp schulcloud_calendar_db

Test local mailing​

Local Files Storage​

  1. Clone repository and perform installation as described in repo readme: https://github.com/hpi-schul-cloud/file-storage

  2. Start the service

    npm run start:files-storage:dev

  3. In the legacy client, the value of "CORS" must be set to false in the ".env" file, otherwise an upload via the old service is not possible.

  4. Minio is used here as local storage.

    Execute the following command via local terminal to create a storage via Minio, which is then accessible via http://localhost:9000:

    docker run \
      --name minioS3storage \
      -p 9000:9000 \
      -p 9001:9001 \
      -e "MINIO_ROOT_USER=miniouser" \
      -e "MINIO_ROOT_PASSWORD=miniouser" \
      quay.io/minio/minio server /data --console-address ":9001"

Local Legacy File System​

Minio must be set up, see "Local Files Storage"

  1. After seeding the local database (for example via the command "npm run setup:db" in the server repository), a collection named "storageproviders" must still be created, as there is no seed data for it with the necessary credentials (security aspect). The following document should then be inserted into this collection:

    storageproviders collection:

    {
        "_id" : ObjectId("62949a4003839b6162aa566b"),
        "isShared" : true,
        "region" : "eu-central-1",
        "type" : "S3",
        "endpointUrl" : "http://localhost:9000",
        "accessKeyId" : "miniouser",
        "secretAccessKey" : "<secret>",
        "maxBuckets" : 150.0,
        "freeBuckets" : 138.0,
        "createdAt" : ISODate("2021-02-09T09:30:42.507+0000"),
        "updatedAt" : ISODate("2022-05-30T10:28:48.970+0000"),
        "__v" : 0.0
    }

    Note: You can use <workspace>/scripts/secret.js to generate a valid secret key. Please note that your Minio account is also linked up.

  2. For this to be used, the appropriate provider must be entered in the "schools" collection in the respective school being used. Let's assume we want to use the user "lehrer@schul-cloud", then we go to the school named "Paul-Gerhardt-Gymnasium" and supplement the document there with the additional attribute and appropriate value from the storageprovider document created above:

    schools collection:

    "storageProvider" : ObjectId("62949a4003839b6162aa566b")

  3. Now both the new and the old file service can be used.

Generate image previews​

The File Storage Service uses Imagemagick to generate preview images. For preview images to be generated, Imagemagick must be installed locally.

This script installs Imagemagick with support for heic files (also works under WSL).

p.s.: If no preview is displayed - because it is still blocked by virus scan -, then in MongoDB: fileRecord.securityCheck.status can be overwritten with verified.

Local antivirus via Docker​

To run ClamAV locally as antivirus scanner - it is sufficient to start a corresponding Docker container as follows:

docker run -d -p 3310:3310 mkodockx/docker-clamav:alpine

Set up Redis​

In our deployments we use Redis for caching. Locally, Redis is not absolutely necessary. If Redis is not set up locally, an in-memory store is used by default, which does not need to be set up separately.

If Redis is to be used locally, the following steps are necessary for setup:

  1. Start Redis as Docker container or install locally.
  2. In the server, enter the URL of Redis as default under REDIS_URI in default.schema.json (normally: redis://localhost:6379).
  3. In the Legacy Client, enter the URL of Redis as default for REDIS_URI in config/global.js.

Set up SuperHero Dashboard​

Prerequisite: clone the repo from https://github.com/hpi-schul-cloud/superhero-dashboard

To work with the SuperHero Dashboard (SHD) - which is basically used as a database layer for editing user data for non-devs - there are a few things to consider since using Node version 20.

Under Windows: Many packages used in the SHD are very outdated and require the installation of additional C++ packages to install the dependencies of the repository. Here it is best to work along the error log and install the respective packages afterwards.

Under Mac: For the same reason, the package "distutils" is used here, which is normally covered by the Python installation, but has not been included there since Python 3.12. Here you have to go a separate way to get the necessary functionalities. It is best to use one of the following ways using homebrew under macOS.

  1. The installation of brew install python-setuptools, in the hope that everything necessary was installed there.
  2. If 1. doesn't work, you should use the old Python version using brew install python@3.11 then the corresponding Env Var must be set in ".zshrc". Either with export PYTHON=3.11 or export npm_config_python=/opt/homebrew/bin/python3.11, if necessary, both can be used at the same time, nothing can break for now.